---
title: Installation
description: "How to install and set up the VibeKit CLI on your system"
---

## Prerequisites

Before installing the VibeKit CLI, ensure you have:

- **Node.js** version 18.0.0 or higher
- **npm** or **yarn** package manager
- **Docker** installed and running (optional, for maximum security)
- **Claude Code CLI** or **Gemini CLI** for the agents you want to use

## Installation Methods

### Global Installation (Recommended)

Installing globally makes the `vibekit` command available system-wide:

<CodeGroup>
```bash npm
npm install -g vibekit
```

```bash yarn
yarn global add vibekit
```

```bash pnpm
pnpm add -g vibekit
```
</CodeGroup>

### Project Installation

For project-specific installations:

<CodeGroup>
```bash npm
npm install --save-dev vibekit
```

```bash yarn
yarn add --dev vibekit
```

```bash pnpm
pnpm add -D vibekit
```
</CodeGroup>

### Using npx (No Installation)

Run commands without installing:

```bash
npx vibekit claude "Generate a REST API"
npx vibekit dashboard
```

## Verify Installation

After installation, verify that the CLI is working:

```bash
# Check version
vibekit --version

# View help
vibekit --help
```

## Post-Installation Setup

### 1. Install Required Agents

Install the coding agents you want to use:

```bash
# Install Claude Code CLI
npm install -g @anthropic/claude-code

# Install Gemini CLI (if available)
# Follow Gemini CLI installation instructions
```

### 2. Configure Environment Variables

Set up your API keys:

```bash
# For Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# For Gemini
export GOOGLE_API_KEY="..."

# For proxy configuration (optional)
export HTTP_PROXY="http://proxy.example.com:8080"
```

Or add them to your shell profile (`~/.bashrc`, `~/.zshrc`):

```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
```

### 3. Configure Settings (Optional)

Run the settings interface to configure VibeKit:

```bash
vibekit
```

This allows you to:
- Enable/disable Docker sandbox
- Configure proxy server settings
- Enable/disable analytics
- Set up global aliases

### 4. Docker Setup (Optional)

For maximum security, ensure Docker is running:

```bash
# Check Docker status
docker info

# Start Docker daemon if needed
# On macOS: Open Docker Desktop
# On Linux: sudo systemctl start docker
```

## Troubleshooting Installation

### Command Not Found

If `vibekit` command is not found after global installation:

<Tabs>
  <Tab title="npm">
    ```bash
    # Check npm global bin directory
    npm config get prefix

    # Add to PATH (example for macOS/Linux)
    export PATH="$(npm config get prefix)/bin:$PATH"

    # Make permanent by adding to ~/.bashrc or ~/.zshrc
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    # Check yarn global bin directory
    yarn global bin

    # Add to PATH
    export PATH="$(yarn global bin):$PATH"
    ```
  </Tab>
</Tabs>

### Permission Errors

If you encounter permission errors during global installation:

```bash
# Option 1: Use a Node version manager (recommended)
# Install nvm: https://github.com/nvm-sh/nvm
nvm install node
npm install -g vibekit

# Option 2: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g vibekit
```

### Docker Not Running (Optional)

If you want to use Docker sandbox and see Docker-related errors:

```bash
# Check if Docker is installed
docker --version

# Check if Docker daemon is running
docker ps

# Start Docker
# macOS: Open Docker Desktop application
# Linux: sudo systemctl start docker
# Windows: Start Docker Desktop
```

### Agent Not Found

If you see "command not found" errors for Claude or Gemini:

```bash
# For Claude Code CLI
npm install -g @anthropic/claude-code

# Verify installation
claude --version

# Set up global aliases (optional)
vibekit setup-aliases
```

## Platform-Specific Notes

### macOS
- Docker Desktop is recommended
- May need to grant terminal permissions for Docker
- Homebrew users can install Node.js with `brew install node`

### Linux
- Add your user to the docker group: `sudo usermod -aG docker $USER`
- Log out and back in for group changes to take effect
- Some distributions may require `sudo` for global npm installs

### Windows
- Use WSL2 for best compatibility
- Docker Desktop with WSL2 backend is recommended
- Run commands in WSL2 terminal, not Command Prompt

## Updating the CLI

To update to the latest version:

<CodeGroup>
```bash npm
npm update -g vibekit
```

```bash yarn
yarn global upgrade vibekit
```

```bash npx
# npx always uses the latest version
npx vibekit@latest
```
</CodeGroup>

## Uninstalling

To remove the CLI:

<CodeGroup>
```bash npm
npm uninstall -g vibekit
```

```bash yarn
yarn global remove vibekit
```
</CodeGroup>

## Next Steps

After installation, you're ready to:

1. [Configure settings](/cli/configuration-files) with `vibekit`
2. [Run your first agent](/cli/quick-reference) with `vibekit claude "Hello world"`
3. [Set up monitoring](/cli/quick-reference) with `vibekit dashboard`

For a quick overview of all commands, see the [Quick Reference](/cli/quick-reference).